Change Recipes

Concrete change paths for common contribution scenarios, plus a contributor checklist.

Use these recipes to route changes through the correct modules without crossing layer boundaries.

Add or Modify a Session Workflow🔗

  1. Keep frontend-neutral request/result models and programmatic operations in crates/ag-session/.
  2. Update Agentty orchestration in crates/agentty/src/app/session/ and adapt it through crates/agentty/src/app/session_api.rs.
  3. Route background-callable operations through the bounded actor in crates/agentty/src/app/session_runtime.rs; do not share App behind an async mutex.
  4. Keep persistence in crates/ag-store/src/ domain modules. Use repository.rs for repository bundle composition and connection.rs for pool wiring; keep Agentty's crates/agentty/src/infra/db.rs limited to database-location and clock composition.
  5. Keep git operations behind GitClient in crates/ag-git/src/client.rs.
  6. Preserve the session-branch invariant: one evolving commit per session branch, with the first file-changing turn creating it and later file-changing turns updating it by amending HEAD.
  7. Update docs when lifecycle/status behavior changes: docs/site/content/docs/usage/workflow.md.

Add a New Agent Backend or Model🔗

  1. Declare model ids, descriptions, provider order, speed support, and known context budgets together in the catalog in crates/ag-session/src/agent.rs. Keep provider defaults and retired-id mappings explicit; removing a public enum variant is a Rust API change even when saved ids remain compatible.
  2. For a new backend, add behavior in crates/ag-agent/src/agent/ and register it in crates/ag-agent/src/agent/provider.rs. Existing backends consume catalog capabilities instead of maintaining their own model lists.
  3. Keep transport selection, parsing, streaming, and provider setup in the provider registry; application workflows continue through worker clients.
  4. Update docs/site/content/docs/agents/backends.md with backend/model documentation.
  5. Keep explicit expectations in model, default, and retirement tests. Use the ag-session test-utils fixtures for unrelated workflows so model replacements do not require editing each test.

Add a Built-in ag-router Model🔗

  1. Add the model's wire capabilities and reasoning mapping in crates/ag-router/src/provider.rs; keep provider HTTP and response decoding in ag-router.
  2. Add local HTTP tests for the schema format, image and tool capabilities, reasoning fields, and error mapping. Keep harness tool execution and permissions in ag-harness.
  3. Expose the built-in model through ag-harness configuration only if the harness supports its capabilities; Agentty product integration still follows the worker and runtime boundary.
  4. To offer it in Agentty Harness sessions, add it to the Harness entries of the ag-session model catalog and declare its ModelProfile in crates/ag-agent/src/agent/model_profile.rs; an ag-agent test rejects ids the harness catalog does not know.

Add or Change a Utility Agent Prompt🔗

  1. Submit an owned OneShotRequest through the worker RunClient; do not select a CLI, app-server, backend, or protocol-repair helper from application orchestration.
  2. Inject &dyn RunClient into the smallest workflow helper that needs deterministic coverage and test it with MockRunClient.
  3. Keep provider routing, protocol repair, usage aggregation, and runtime cleanup in crates/ag-agent/src/agent/submission.rs.

Add a Keybinding or Mode Interaction🔗

  1. For basic text editing, add or update the semantic command in crates/agentty/src/domain/input.rs, then map terminal keys once in crates/agentty/src/runtime/mode/input_key.rs.
  2. Let prompt, question, branch-publish, and settings input modes intercept only their context-specific actions before falling back to the shared input command mapping.
  3. For other interactions, update the handler in crates/agentty/src/runtime/mode/, or in crates/agentty/src/runtime/key_handler.rs when the interaction is a cross-mode overlay dispatch.
  4. If a new mode/state is needed, extend crates/agentty/src/presentation/app_mode.rs.
  5. If help content changes, update crates/agentty/src/presentation/help_action.rs as needed.
  6. Update docs/site/content/docs/usage/keybindings.md.

Add or Change Database Schema🔗

  1. Add a new migration file in crates/ag-store/migrations/ (NNN_description.sql).
  2. Never modify existing migration files.
  3. Keep query changes in the matching crates/ag-store/src/*.rs domain module instead of expanding Agentty's composition facade.
  4. Ensure any status/model behavior changes are reflected in docs pages affected by user-facing behavior.

Add a New UI Page or Component🔗

  1. Add the page in crates/agentty/src/ui/page/ or component in crates/agentty/src/ui/component/.
  2. Wire the page into crates/agentty/src/ui/router.rs.
  3. If a new AppMode is needed, extend the shared presentation contract implemented in crates/agentty/src/presentation/app_mode.rs and exported through crates/agentty/src/presentation.rs, then add a key handler in crates/agentty/src/runtime/mode/.

Contributor Checklist for Architecture-Safe Changes🔗

  1. Follow Module Map for layer ownership and Testability Boundaries for external-system injection.
  2. Update the relevant user guide for visible changes and the canonical architecture page when its contracts change. Keep durable scope instructions aligned.
  3. Reuse cached derived data on render hot paths; measurement and painting must agree.
  4. Keep the runtime key-types table current when execution contracts change, and the boundary reference current when external traits change.
  5. Run the required gates in root AGENTS.md.

Change run execution🔗

  1. Update shared lifecycle contracts in ag-contracts and provider behavior in ag-agent.
  2. Keep mailboxes, session runtime ownership, scheduling, cancellation, and recovery in ag-worker; implement product-specific question, Git, forge, and UI policy in the host adapter. Submit session turns through SessionRunClient and utilities through RunClient.
  3. Import execution contracts from ag-contracts and selections from ag-session. Construct ag-agent adapters only inside ag-runtime; applications configure workers.
  4. Extend headless contract tests and the affected Agentty workflow tests. Changes to operation persistence also need ag-store adapter tests.

Adding model-assisted work🔗

Use the utility prompt recipe. Background work must capture purpose and session/project ownership with ag-worker::scoped_client. Nested utilities retain parent cancellation and run directly under worker supervision, without enqueueing behind the session command awaiting them.

See Execution for the execution contract.